Inside Macintosh: Macintosh Toolbox Essentials
Previous | Chapter Top | Chapter Contents | Next |
You can send events to other applications or processes using the PostHighLevelEvent function (PostHighLevelEvent) . To send Apple events to other applications, use the Apple Event Manager function AESend . The Operating System Event Manager also provides the PPostEvent (PPostEvent) and PostEvent (PostEvent) functions for posting low-level events to the Operating System event queue. The PostEvent function is used by the Toolbox Event Manager. In most cases, your application should not use the PostEvent function.
You can use the PostHighLevelEvent function to send a high-level event to another application.
pascal OSErr PostHighLevelEvent (EventRecord *theEvent,
unsigned long receiverID,
unsigned long msgRefcon,
void *msgBuff,
unsigned long msgLen,
unsigned long postingOptions);
The PostHighLevelEvent function posts the high-level event to the specified process.
If the application to which you are sending a high-level event terminates, you receive the result code sessionClosedErr the next time your application calls PostHighLevelEvent to send another high-level event to the terminated application. If you do not care about any state information about that session, you can just resend your event. Otherwise, you must restart another session and resend your event.
If your application is running in the background and posts a high-level event that requires the network authentication dialog box to be displayed, PostHighLevelEvent returns the noUserInteractionAllowed result code, does not display the network authentication dialog box, and does not send the event. If your application receives the noUserInteractionAllowed result code, you can use the Notification Manager to inform the user that your application needs attention. When the user brings your application to the foreground, you can repost the event. If the reposting is successful, your application can continue to post high-level events without further user interaction. Note that PostHighLevelEvent can return noUserInteractionAllowed only on the first posting of a high-level event to a remote target.
The PostHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion routine or VBL task.
The trap macro and routine selector for the PostHighLevelEvent function are
_OSDispatch
|
In most cases, your application does not need to post events in the Operating System event queue; however, if you must do so, you can use the PPostEvent function.
pascal OSErr PPostEvent (EventKind eventCode,
UInt32 eventMsg,
EvQElPtr *qEl);
In the eventCode and eventMsg parameters, you specify the value for the what and message fields of the event's event record. The PPostEvent function fills out the when , where , and modifiers fields of the event record with the current time, current mouse location, and current state of the modifier keys and mouse button.
The PPostEvent function returns, through the qEl parameter, a pointer to the event queue entry of the posted event. You can change any fields of the posted event by changing the fields of its event queue entry. For example, you can change the posted event's modifier keys by changing the value of the evtQModifiers field of the event queue entry.
The PPostEvent function posts only events that are enabled by the system event mask. If the event queue is full, PPostEvent removes the oldest event in the queue and posts the new event.
Do not post any events other than mouse-down, mouse-up, key-down, key-up, auto-key, and disk-inserted events in the Operating System event queue. Attempting to post other events into the Operating System event queue interferes with the internal operation of the Event Manager.
You must set up register A0 and register D0 before invoking PPostEvent . The PPostEvent function returns values in registers A0 and D0.
For a description of the entries in the event queue, see "The Event Queue" .
The Toolbox Event Manager uses the PostEvent function to post events into the Operating System event queue. In most cases, your application should not call the PostEvent function.
pascal OSErr PostEvent (EventKind eventNum,
UInt32 eventMsg);
In the eventNum and eventMsg parameters, you specify the value for the what and message fields of the event's event record. The PostEvent function fills out the when , where , and modifiers fields of the event record with the current time, current mouse location, and current state of the modifier keys and mouse button.
The PostEvent function posts only events that are enabled by the system event mask. If the event queue is full, PostEvent removes the oldest event in the queue and posts the new event.
Note that if you use PostEvent to repost an event, the PostEvent function fills out the when , where , and modifier fields of the event record, giving these fields of the reposted event different values from the values contained in the original event.
Do not post any events other than mouse-down, mouse-up, key-down, key-up, auto-key, and disk-inserted events in the Operating System event queue. Attempting to post other events into the Operating System event queue interferes with the internal operation of the Event Manager.